CMaster provides an interface for programmers to quickly and easily add their own special functions to CMaster, which can then be accessed from an XTRN menu, a XTRN popup, or by keybindings done in the Keyboard Equivalents menu. In fact, you can compile an XTRN, merge it into an existing XTRN file, and instantly test it from within THINK C (in fact, you can test it on the front source file of the external itself!.)
XTRNs can also modify events before CMaster sees them and/or after CMaster sees (and perhaps modifies them). They can also get called just as a window opens, and just after it closes as well as double-clicks on a Projector ICON. If these XTRNs have no menu titles, then they are "hidden" in that a user would not see them through the human interface (menu or key equivalent.)
First, to use CMaster externals, also called XTRNs, create a folder called "CMaster Externals" in the same folder as your "CMaster Prefs" file. All externals must reside in this folder. Externals must have a type of XTRN and if you use a creator of CMst they will get a generic CMaster External Icon (you must rebuild the desktop after having installed CMaster 2.0 to get this).
CMaster XTRNs have a user interface similiar to that provided by the CMaster icon features, in that they may have as much as 10 different variations (depending on key modifiers), and a key can be bound to each variation [sorry, no icon support at this time.] Likewise, you can change the modifiers while viewing the XTRN menu, and the items will change in real time.
CMaster External files include resources, some required, and others which you may include under certain constraints. The required resources include a PROC (executable resource), a xitm (menu titles and a few flags), and a STR# (help items for the Keyboard Equivalent and Balloon help menus). These must all be item number 128. You can add any other resources you'd like (PREF, DLOG, etc) as long as they are numbered between 128->159. You can have other PROC and STR# resources numbered 129->159.
CMaster reads the XTRN folder modification time (only) at boot, and if it has changed since the last time CMaster looked at it, it examines each XTRN file to see if its modification date is newer than a cached date. It then may copy all resources into the CMaster Prefs file (or update them), renumbering all resources somewhere in the 20000 range. Each XTRN gets a range of 32 assigned to it. As you add and delete XTRNs, their resource range may change. CMaster always passes the current base number to each XTRN (which may change from call to call as you add or delete XTRNs.) Thus, the programmer must not hard-code the resource ID of dialogs, alerts, etc, but must reference them off the "resID" value passed to it.
Some resources have embedded references to other resources, and they must be altered when the resource numbering changes. CMaster currently can handle these types: "DLOG", "DITL", "ALRT", and "hdlg". CMaster always keeps the resource fork of the CMaster Prefs file open, as it usually looks first there for resources (allowing you to override many of the CMaster defaults resources, like 'FUNC' numbers, TEXT AppleScript header, and the sounds.)
CMaster remembers which resources were copied from the original XTRN file, so a resource can "AddResource()" items (in the "resID" -> "resID" + 31 range). These items are semi-permanent, in that they will persist when CMaster reloads an XTRN which it already had loaded, but which was detected out of date. Thus, an XTRN might prompt the user for some text strings that it would save in "STR " resources, which it would "AddResource" to add to the CMaster Prefs file (this file is foremost in the Resource File Chain.)
Once the XTRN resource file has been built, move it to the "CMaster XTRNs" folder, and launch THINK C (or reload a project)—CMaster will load the XTRN file. All XTRNs get an INIT message (when they could allocate memory, or whatever) when they load, and a QUIT message either when CMaster is shutting down, or they are about to be reloaded (you should deallocate memory here). Use RememberA0/SetUpA4/RestoreA4 to use globals in a PROC.
CMaster can handle as many XTRN functions as THINK's heap will allow. They load in alphabetical order, and appear in the XTRN menu in the same order. See the example for more information.
// Action List to Use XTRNs
1) Create a folder called "CMaster Externals" in the same folder as the CMaster prefs file.
2) Create one of more files of type XTRN and creator CMst and place in the CMaster Externals folder.
3) Restart THINK or reload a project.
4) Access your XTRN from the XTRN menu, the XTRN popup, or use the Keyboard Equivalents to create key bindings (which will persist.)
5) Oops, you found a bug (we hope in your code, not ours!)
6) Rebuild the XTRN and use the "merge" option to merge it into its file in the "CMaster Externals" folder.
7) CMaster "DoneBeeps" to signal that the XTRN has reloaded.
8) Test again!
// If Errors...
If, while adding or deleting externals, things go bad, use the "XTRN, delete resources" Key Function so you can wipe the resources of the XTRN files and reload them all from scratch. This action both cleans the CMaster Pref resource fork of all XTRN related resources, and removes all Keyboard bindings to the externals-use it as a last resort.
